home *** CD-ROM | disk | FTP | other *** search
/ Internet Tools (InfoMagic) / Internet Tools.iso / security / ipacl.README < prev    next >
Text File  |  1993-12-16  |  11KB  |  308 lines
  1. What is IPACL ?
  2. ---------------
  3.  
  4.     IPACL stands for `IP access list'. It has been designed
  5.     to filter incoming and outgoing TCP/UDP packets in
  6.     the SVR4/386 kernel with Lachamnn Streams TCP.
  7.     Depending on source/destination addresses and port numbers
  8.     packets can be passed through or dropped.
  9.     We run IPACL on Interactive SVR4 and on SINIX-L
  10.     (on MX300 (Intel)). I believe, that it should be easy to
  11.     port IPACL to other SVR4 bases systems, e.g. the new Solaris.
  12.  
  13. Architecture
  14. ------------
  15.  
  16.     Due to the modularity provided by AT&T's streams
  17.     concept this module could be written without
  18.     modifying any of the TCP/IP kernel sources
  19.     (You just have to install the driver and relink the kernel).
  20.     The access list module will be autopushed on /dev/ip
  21.     whenever this device is opened.
  22.     An IOCTL interface in the driver provides a facility
  23.     to download a filter program into the kernel module
  24.     (The utility command /usr/sbin/ipacl reads and compiles
  25.     a configuration file and downloads the resulting filter
  26.     program into the kernel).
  27.     All TCP and UDP packets that are sent/recived (via IP)
  28.     have to pass the access list module.
  29.     Unfortunately there is no way to filter packtes, when
  30.     your host acts as router (IPFORWARDING != 0), because
  31.     IP will not pass packets, that are to be forwarded, up
  32.     to TCP or UDP.
  33.     ICMP packetes cannot be filtered by a user supplied
  34.     filter program, but are handled in the following way:
  35.     REDIRECT packetes will be dropped and all other ICMP
  36.     packets will be passed through.
  37.     For my application, that did not worry, because I only wanted
  38.     to control access to the host, where IPACL is installed.
  39.  
  40.     +----------+----------+----------+
  41.     | TCP      | UDP      | ICMP     |         
  42.     +----------+----------+----------+
  43.     | IPACC                          |
  44.     +--------------------------------+
  45.     | IP                             |
  46.     +--------------------------------+
  47.     | Network interfaces ...         |
  48.     +----+-----+-----+---------------+
  49.          |     |     |    ...
  50.          |     |     |
  51.         LAN   SLIP   etc. ...
  52.  
  53. Source files
  54. ------------
  55.  
  56.     COPYING             GNU general public license
  57.  
  58.     Driver.c            The streams module, that sits between
  59.                         /dev/tcp, /dev/udp and /dev/ip
  60.  
  61.     Makefile            The makefile
  62.  
  63.     Master              Kernel configuration files for the
  64.     System              ipacc-Driver - written according to the
  65.                         SVR4 conventions
  66.  
  67.     README              The file you are currently reading
  68.  
  69.     S69ipacl            Startup script, called at boot time
  70.  
  71.     gram.doc            Brief overview of the configuration
  72.                         file grammar. To get an exact definition
  73.                         of the grammar look at the yacc/lex
  74.                         sources in ipacl.[yl]
  75.  
  76.     ipacl.cfg           The default configuration file -
  77.                         does not filter any packets
  78.  
  79.     ipacl.l             Lexical analyzer for the
  80.                         configuration file - part of the
  81.                         utility program /usr/sbin/ipacl
  82.  
  83.     ipacl.y             Parser for the configuration file -
  84.                         part of the utility program /usr/sbin/ipacl
  85.  
  86.     matcher.c           Interpreter for the filter
  87.                         program (in the kernel)
  88.  
  89.     matcher.h           Header file for matcher.c
  90.  
  91.     pkg                 This directory contains all the
  92.                         stuff necessary to build a SVR4 package
  93.  
  94.     sample.cfg          Sample configuration file, this file will
  95.                         give you an overview how to write a
  96.                         configuration file for IPACL.
  97.  
  98. Compiling and installing IPACL
  99. ------------------------------
  100.  
  101.     - First look at the Makefile, maybe you have to
  102.       change something (e.g. you want to use another C compiler).
  103.  
  104.     - Type `make' to compile the sources.
  105.  
  106.     - Type `make package' to build the SVR4 package.
  107.       The package will be built in the default package spool
  108.       directory (normally /var/spool/pkg).
  109.       (You need write access to the package spool
  110.       directory - either do it as root or do a chmod on
  111.       the directory).
  112.  
  113.     - Type `pkgadd ipacl' to install the package that has
  114.       been built in the previous step.
  115.       (Must be run as root).
  116.  
  117.     - Relink your kernel (type `/etc/conf/bin/idbuild').
  118.       (pkgadd should do this - but it is not yet implemented
  119.       in the install scripts).
  120.       (Must be run as root).
  121.  
  122.     - Edit the IPACL configuration file in /var/ipacl/ipacl.cfg.
  123.       (Must be run as root).
  124.  
  125.     - Reboot your system (type `init 6').
  126.       (Must be run as root).
  127.  
  128. Components
  129. ----------
  130.  
  131.     The installed binaries of IPACL consist of the following
  132.     components:
  133.  
  134.     - /etc/conf/...
  135.  
  136.         This is the standard place, where SVR4 drivers, master and
  137.         system files reside. The driver name of the IPACL streams
  138.         module is `ipacc'. The file names, where to find the
  139.         diriver componets in the /etc/conf subtree follow the
  140.         SVR4 conventions  (/etc/conf/pack.d/ipacc/*,
  141.         /etc/conf/sdevice.d/ipacc, ...).
  142.  
  143.     - /etc/ap/chan.ap
  144.  
  145.         This is a configuration file for the autopush command.
  146.         It is invoked the following line in /etc/inittab.
  147.  
  148.             ap::sysinit:/sbin/autopush -f /etc/ap/chan.ap
  149.  
  150.         The postinstall script of IPACL edits this file and
  151.         adds some entries to autopush `ipacc' onto /dev/ip.
  152.         E.g. postinstall adds the following lines to
  153.         /etc/ap/chan.ap (note that 24 is the major number of /dev/ip).
  154.  
  155.             # ipacc +++ do not edit this line
  156.             # push ipacc over /dev/dip
  157.             24  0       255     ipacc
  158.             # ipacc --- do not edit this line
  159.  
  160.         When the IPACL package is removed, the lines given above
  161.         will be deleted from this file.
  162.  
  163.         When you have another (e.g. vendor specific) version
  164.         of SVR4, it may be possible, that you will have to modify
  165.         something to setup autopush correctly.
  166.  
  167.     - /usr/sbin/ipacl
  168.  
  169.         This command parses the configuration file, produces
  170.         a binary filter program and loads this program down
  171.         into the ipacc driver.
  172.  
  173.         The command takes no arguments. The configuration
  174.         file has to be supplied on stdin, error messages
  175.         will be printed to stderr and on stdout there will be
  176.         printed an assembler listing of the generated filter program.
  177.  
  178.     - /var/ipacl/ipacl.cfg
  179.  
  180.         IPACL configuration file, that will be downloaded into
  181.         the kernel at boot time.
  182.  
  183.     - /etc/rc2.d/S69ipacl
  184.  
  185.         This script will be executed at system startup time and
  186.         load /var/ipacl/ipacl.cfg into the kernel.
  187.  
  188. Configuration file
  189. ------------------
  190.  
  191.     Definitions:
  192.  
  193.         Address: An address in the IPACL config file is a tuple
  194.                  consisting of an internet address and a mask.
  195.                  Internet addresses can be specified in dotted
  196.                  notation or as host names, that will be resolved
  197.                  to internet adresses with gethostbyname().
  198.                  Masks can be specified in hex.
  199.                  You can also use a network specification (either
  200.                  in dotted notation or as network name from
  201.                  /etc/networks) to specify both parts
  202.                  of an IPACL address at once.
  203.  
  204.         Port:    A port in the IPACL config file is a tuple
  205.                  consisting of the protocol (tcp/udp) and
  206.                  a 16 bit port number.
  207.  
  208.         Sets:    IPACL allow you to define sets of addresses or
  209.                  ports.
  210.  
  211.     The configuration file consists of
  212.  
  213.         - declarations and
  214.         - statements
  215.  
  216.     Declarations:
  217.  
  218.         You can use a declaration to assign a symbolic name to
  219.         an address, a port, an address set or a port set.
  220.  
  221.     Statements:
  222.  
  223.         The statements describe, how packets are to be filtered.
  224.         They are a kind of assembly notation of the filter program.
  225.  
  226.         accept                          Accept the current packet
  227.                                         and pass it through. No further
  228.                                         statements will be executed for
  229.                                         this packet.
  230.  
  231.         deny                            Do not accep (drop) the current
  232.                                         packet. No further statements
  233.                                         will be executed for this packet.
  234.  
  235.         <cond> -> accept                If <cond> is true, then accept
  236.                                         the current packet.
  237.  
  238.         <cond> -> deny                  If <cond> is true, then drop
  239.                                         the current packet.
  240.  
  241.         <cond> -> <label>               If <cond> is true, then
  242.                                         goto <label>.
  243.  
  244.         The condition <cond> can test, wheter
  245.  
  246.             - the src/dst address of the packet matches a given
  247.               address.
  248.               The comparison is done in the following way:
  249.               (address-from-packet & address.mask) == address.address
  250.  
  251.             - the src/dst address of the packet does not match a given
  252.               address.
  253.  
  254.             - the src/dst address of the packet is (or is not) a member
  255.               of a given set of addresses.
  256.  
  257.             - the src/dst port of the packet is (or is not) a member
  258.               of a given set of ports.
  259.  
  260.             - the src/dst port of the packet is ==, !=, >, <, >=, <=
  261.               a given port.
  262.               Note, that the condition `src >= port 1024/tcp' means
  263.               protocol-in-packet == tcp && src-port-in-packet >= 1024.
  264.               Therefore `src < port 1024/tcp' is *not* the opposite
  265.               of the above condition ! This applies to the operators
  266.               <, >, <= and >=.
  267.  
  268.     The file gram.doc gives a brief description of the grammar.
  269.     A detailed description of the grammar you will find in the
  270.     lex/yacc sources ipacl.[yl] itself.
  271.     Example.cfg is a configuration file example.
  272.  
  273. Bugs
  274. ----
  275.  
  276.     - Sorry, but there exists no documentation at all.
  277.  
  278.     - The syntax for the configuration file is a little bit '&"%$'& -
  279.       it is a kind of assembler language to describe the filter
  280.       program and does not provide high level features.
  281.  
  282.     - Some parts of the program are really coded *dirty*, e.g.
  283.       fixed size arrays are used to hold some data structures and
  284.       there are no overflow checks, ...
  285.       (That's not the normal way I do programming, but IPACL
  286.       was a quick and dirty development and I never thouhgt, that
  287.       I would release ist).
  288.  
  289.     - IPACL silently drops packets, that are not allowed (and prints
  290.       a kernel message to the console). Perhaps an ICMP host unreach
  291.       message should be sent back to the sender of the packet,
  292.       but sometimes this is not desirable.
  293.  
  294.     - Forwarded packetes (IPFORWARDING != 0) cannot be filtered.
  295.  
  296. Comments, bug reports, ...
  297. --------------------------
  298.  
  299.     If you have any comments, find bugs, have some questrions, etc.,
  300.     then send mail to
  301.  
  302.         fuer@siemens.co.at
  303.  
  304.     When you make some improvements to IPACL, that might be
  305.     interresting for me or anyone else, I would be appreciated
  306.     to get a copy of the modified version too.
  307.  
  308.